Forestry CMS Blocks Field Demo

Foresty CMS allows content editors to easily manage a staticly generated site without needing to know markdown or HTML. This works really well if you’re just editing a page with a title and a body, but sometimes you need to offer more diversity. Luckily Forestry has a Block Field which allows a content editor to easily add robust content to a page. The example below shows how we can create a block field that displays highlights anywhere on a page.

forestry block field exampleClick to expand

0. Prerequisites

This tutorial assumes you have a site up and running on Forestry. I will be using Jekyll in this tutorial, but Forestry works with all major static site generators.

1. Create a New Front Matter Template to Be Used as a Block

In order to use a block field, you first need to create a front matter template.

Front Matter Templates (FMTs) enable developers to fully customize the interface of the Markdown and HTML editors. You can think of them as the content model for your front matter.

  1. Under the Front matter section on the sidebar, click Add Template, and select blank template. creating a new front matter templateClick to expand
  2. Set the name to Highlights and select Fields. adding a new front matter fieldClick to expand
  3. On the next screen, click Add Field and select Repeatable Field Group selecting repeatable field groupClick to expand
    1. Set the label to Highlights. Make sure the name is highlights. adding a repeatable field group label and nameClick to expand
    2. Set the Minimum value to 3 under the Validation tab.
      adding validation to repeatable field groupClick to expand
    3. Click Add Field to "Highlights" repeatable field group formClick to expand
    4. Select Textfield field optionsClick to expand
    5. Set the Label to Headline and the Name to headline. field optionsClick to expand
    6. EnableRequired under the Validation tab.
      field validation optionsClick to expand
    7. Click Add Field to "Highlights" again.
    8. Select Textfield field optionsClick to expand
    9. Set the Label to Description and the Name to description. field optionsClick to expand
    10. Enable Textarea/WYSIWYG under the Widget tab. field optionsClick to expand
    11. Click Add Field to "Highlights" again.
    12. Select Textfield field optionsClick to expand
    13. Set the Label to URL and the Name to url.

The final configuration should look something like this:

field optionsClick to expand

2. Create a New Front Matter Template to Be Used as When Editing Pages

We now need to create a template for Pages on our site. This template will have a Block field that will contain the Highlights field we just created.

  1. Under the Front matter section on the sidebar, click Add Template, and select blank template. creating a new front matter templateClick to expand
  2. Set the name to Page and select Fields and big content area. creating a new front matter templateClick to expand
  3. On the next screen, click Add Field and select Blocks selecting blocks fieldClick to expand
    1. Set the label to Page Sections. Make sure the name is page_sections. adding a block field label and nameClick to expand
    2. Under the Blocks tab, select the Highlights we created in the previous steps. adding a front matter templates to block fieldClick to expand

3. Assign The Page Template to Jekyll Pages

Now that we have a template that contains Block fields, we need to make this template available any Page on our site.

  1. Under the Settings section on the sidebar, navigate to the Sidebar tab, and click Pages.
  2. Add the Page template we created in the previous steps to the Available Templates field. updating page templateClick to expand

5. Add Block Content To a Page, and Pull The Changes Locally.

Now all Pages in your site have a Page Sections field that allows you to add highlights. Go ahead and add some highlights to a page and save.

page with page sectionsClick to expand

Once saved, run git fetch; git pull to pull in the new content and configuration.

Note that the page you edited should have a page_sections: key in the front matter with a list of nested highlights:.


# index.md

---

title: Forestry CMS Blocks Field Demo
description: This repository demonstrates how to use Forestry's Blocks Field to create
rich layouts.
page_sections:

- template: highlights
  highlights:

  - headline: Free
    description: |-

    ## $0 / mo

    - 10 users included
    - 2 GB of storage
    - Email support
    - Help center access
      url: https://example.com

  - headline: Pro
    description: |-

    ## $15 / mo

    - 20 users included
    - 10 GB of storage
    - Priority email support
    - Help center access
      url: https://example.com

  - headline: Enterprise
    description: |-

    ## $29 / mo

    - 30 users included
    - 15 GB of storage
    - Phone and email support
    - Help center access
      url: https://example

---

# Forestry CMS Blocks Field Demo

This repository demonstrates how to use Forestry's [Blocks Field](https://forestry.io/docs/settings/fields/#blocks) to create rich layouts.

You’ll also notice a .forestry/front_matter/templates/highlights.yml and .forestry/front_matter/templates/page.yml files. These were created by Foresty when we created our Front Matter templates. We could have created these files manually, but it’s easier to make them with the Forestry GUI.

# .forestry/front_matter/templates/highlights.yml

---

label: Highlights
hide_body: true
fields:

- name: highlights
  type: field_group_list
  fields:
  - name: headline
    type: text
    config:
    required: true
    label: Headline
  - name: description
    type: textarea
    default: ''
    config:
    required: false
    wysiwyg: true
    schema:
    format: markdown
    label: Description
  - name: url
    type: text
    config:
    required: false
    label: URL
    config:
    min: '3'
    max:
    labelField:
    label: Highlights

# .forestry/front_matter/templates/page.yml

---

label: Page
hide_body: false
fields:

- name: title
  type: text
  config:
  required: true
  label: Title
- name: description
  type: textarea
  default: ''
  config:
  required: false
  wysiwyg: false
  schema:
  format: markdown
  label: Description
- name: page_sections
  type: blocks
  label: Page Sections
  template_types:
  - highlights
    config:
    min:
    max:

4. Display the Block Field Content

Now that we have our block field data stored in front matter, we need to have it displayed on the page.

  1. Add the following code to your layout.
    • This code loops through all items stored in the page_sections key on the front matter.
    • It then looks at what template that particular page section is using, and conditionally loads the corresponding partial.
    • We can DRY things up by using the template name in the name of the include by writing include blocks_.html instead of include blocks_highlights.html 
     {% for block in page.page_sections %}
 {% assign template = block.template %}
 {% case template %}
 {% when 'highlights' %}
 {% include blocks_{{template}}.html %}
 {% endcase %}
 {% endfor %}

  2. Create a blocks_highlights.html partial.

    • This is loaded via the {% include blocks_{{template}}.html %} line.
    <div class="row mb-5">
  {% for highlight in block.highlights %}
  <div class="col-md-4">
    <h4>{{highlight.headline}}</h4>
    {{ highlight.description | markdownify}} {% if highlight.url %}
    <a href="{{highlight.url}}" class="btn btn-large btn-primary"
      >Click Here</a
    >
    {% endif %}
  </div>
  {% endfor %}
</div>